home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / The World of Computer Software.iso / tags18.zip / TAGS.DOC < prev    next >
Text File  |  1992-05-10  |  35KB  |  882 lines
  1.  
  2. ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒
  3. ▒┌                                                                          ┐▒
  4. ▒                          Tags Generator V1.8                               ▒
  5. ▒                                                                            ▒
  6. ▒            A TAGS generator for Assembly and C and written in C            ▒
  7. ▒                   V1.8 Dedicated to the Public Domain                      ▒
  8. ▒                                                                            ▒
  9. ▒                              May 10, 1992                                  ▒
  10. ▒                              J. Kercheval                                  ▒
  11. ▒                      [72450,3702] -- johnk@wrq.com                         ▒
  12. ▒└                                                                          ┘▒
  13. ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒
  14.  
  15. 05-10-92
  16.  
  17. This is V1.8
  18.  
  19. Fixed a newly introduced bug in define parsing with the line 
  20. continuation character.  Fixed an error state if continuation
  21. character found within a define and not at the end.  Added the
  22. -j switch to disable the junk filter for those overloading 
  23. standard delimiters in C++ (ie. operator+).  Fixed a problem
  24. with enumeration constants (the last would be skipped unless
  25. followed by a comma).
  26.  
  27.                                     jbk
  28.  
  29. 03-30-92
  30.  
  31. This is V1.7
  32.  
  33. Fixed a number of C parsing bugs, including a problem with the C++
  34. extern "C" {...} statement and a number of small annoyances with
  35. preprocessor directives again.
  36.  
  37. Support was added for V6.0 of Epsilon for the new tag file format.  The
  38. previous format is available via the -o5 output switch.  In addition,
  39. the first line (the tag header) of the output tag file specified via the
  40. -t switch is dealt with correctly (while using the -oe switch).
  41.  
  42.                                     jbk
  43.  
  44. 11-12-91
  45.  
  46. This is V1.6
  47.  
  48. Added a junk filter for the C parser to eradicate unwanted tokens
  49. which were normally delimiters but were being tagged due to syntactic
  50. nuisances introduced through the twisted use of preprocessor
  51. directives and 'soft' syntax errors such as a ';' at the end of a
  52. procedure.  Added the -? switch as a common synonym for -h.
  53.  
  54.                                     jbk
  55.  
  56. 10/07/91
  57.  
  58. This is V1.5
  59.  
  60. The moment you post something, you (or normally, someone else) finds
  61. a bug to let you know what a peon you really are.  V1.4 had problems
  62. with extended enumeration constants and syntactic vagaries regarding
  63. enum declarations.
  64.  
  65.                                     jbk
  66.  
  67. 10/04/91
  68.  
  69. This is V1.4
  70.  
  71. A bug was fixed in assembly tagging (local labels using ':' were
  72. being tagged when defines were enabled regardless of -al flag).
  73. Exclude file parsing (-x flag) was added.  Support for tagging of
  74. enumeration constants and internal static declarations (-ck -ci) was
  75. added.  Improved support of LISTFILES, now the list file may be in
  76. the form of a response file and filenames may be separated by '+',
  77. ',', ';' or whitespace (comments delimited by '#' are still
  78. supported).
  79.  
  80.                                     jbk
  81.  
  82. 10/01/91
  83.  
  84. This is V1.3
  85.  
  86. A bug was fixed in cleanup code executed on Ctrl-C, Break, file
  87. error, or memory allocation error.  In V1.2, one of these errors
  88. normally resulted in some lost chains in the file structure but only
  89. manifested on a failure condition.
  90.  
  91.                                     jbk
  92.  
  93. 9/30/91
  94.  
  95. This is V1.2
  96.  
  97. This code is dedicated to the Public Domain, this means you may use
  98. this code for any purpose and for any reason and without any
  99. warranty, suitability to task, etc.  Public Domain also means that
  100. you may not place your own Copyright on this code.  Do not claim it
  101. to be your work.  Portions of this are under GNU CopyLeft (read the
  102. GNU.DOC file included in this distribution).  In particular the sort
  103. module (sort.c std.h) are under both GNU CopyLeft and individual
  104. Copyright.  If you need to be rid of CopyLeft to use this utility you
  105. will have to roll your own (or obtain another public domain) sort
  106. engine.
  107.  
  108. If you do use this and then make changes, bug fixes, or better still,
  109. add a new language parser (PASCAL, FORTRAN, BASIC come to mind right
  110. off the top) or create a macro for a particular editor to deal with
  111. tag files, then please route these changes to me and I will
  112. incorporate these changes and repost the package.
  113.  
  114. The intent of this utility and the release of its source to the
  115. Public Domain is in the interest of high quality programming and code
  116. generation.  Quality is designed in at the earliest stages and must
  117. be maintained by the use of high quality development and maintenance
  118. tools.  If professionals doing good work devote some talent and time
  119. to projects such as this and other projects then the programming
  120. community as a whole benefits (enough evangelism).
  121.  
  122.  
  123.                                     jbk
  124.  
  125. ------------------------------------------------------------------------------
  126.  
  127. Authors:
  128.  
  129.     J. Kercheval
  130.         johnk@wrq.com
  131.         [72450,3702]
  132.  
  133.         Overview and Architecture
  134.         C Module:
  135.         ASM Module:
  136.         Shell:
  137.         Arglist:
  138.         *IX wildcard:
  139.         Match:
  140.         Flags:
  141.         Tag IO (Format, styles and merge):
  142.         Modifications to Sort module to allow use as separate module
  143.             and some subtle bug fixes.  Context diff in SORTMISC.ZIP
  144.         Epsilon extensions:
  145.  
  146.     Mike Haertel
  147.         Free Software Foundation
  148.  
  149.         Original Sort Module:
  150.  
  151.  
  152.     Kevin Dean
  153.         Fairview Mall P.O. Box 55074
  154.         1800 Sheppard Avenue East
  155.         Willowdale, Ontario
  156.         CANADA    M2J 5B9
  157.  
  158.         CRC Validation Module:
  159.  
  160.  
  161. Contributors:
  162.  
  163.     Leonid Kokin
  164.         leok@wrq.com
  165.  
  166.         Brief macro:
  167.  
  168.  
  169. Thanks:
  170.  
  171.     Shane Hartman
  172.         ksh@ai.mit.edu
  173.     Eric Halpern
  174.         erich@wrq.com
  175.     Tad Marshall
  176.         tad@wrq.com
  177.  
  178.         Beta testing and usability editing for distribution
  179.  
  180. ------------------------------------------------------------------------------
  181.  
  182. Program Description:
  183.  
  184.     This utility implements a tags generator for assembly and C code.
  185. This module has been written for and is designed around the 80x86
  186. platform but is written with platform specific code as isolated as
  187. possible.
  188.  
  189.     Tags are informative lines stored (usually) within an ascii file
  190. and specify three things.  First a tag contains a token or an
  191. identifier which is a definition or declaration within the source
  192. code, second a tag contains the file name where that particular token
  193. is defined and third a typical tag will have an offset into the file
  194. where the token is defined (for example a character offset or a line
  195. number).  Occasionally a tag will be generated for an environment
  196. which likes the actual line which is the definition (GNU Emacs and
  197. Epsilon for example) specified instead of a file offset. This type of
  198. tag is sometimes used and is supported by this generator since, while
  199. it is possible for more than one line in a file to be the same and be
  200. VERY different in context, it has an advantage in that if your source
  201. module changes, the tag will probably still be found.
  202.  
  203.     The resulting tag file is intended to be used by an extensible
  204. editor or browser to traverse (possibly) widely placed code during
  205. planning, creation, maintenance and modification of medium and large
  206. projects.
  207.  
  208.     The tags file is used as an index into source definitions.  The
  209. typical implementation allows the user to place the cursor on the
  210. token to be found, start a macro (usually bound to a key) and have
  211. the editor place the cursor at the location which that token is
  212. defined.  This makes code traversal very simple.  If in addition, the
  213. macro implements a history, then moving around code becomes very
  214. similar to using a hypertext system.
  215.  
  216.     This generator has been designed to be used within a project make
  217. file and has a large number of options designed to make the task of
  218. generating and maintaining a tags file as simple and fast as
  219. possible.  There are three good methods for generating tags out of a
  220. makefile and each method is best for particular situations.  The
  221. examples below use OPUS make scripts as makefile code samples.
  222.  
  223.     1)  The first method is to generate a new tag file every time the
  224.         executable is generated.  This method is the simplest to
  225.         implement and is good for small and very small projects.
  226.  
  227.         This would be accomplished with either a list file or a macro
  228.         within the makefile.  For example:
  229.  
  230.             MYEXE: tags
  231.  
  232.             TAGS:
  233.                 tags -tdefault.tag $(TAGFLAGS) $(SRCS)
  234.  
  235.         or
  236.  
  237.             MYEXE: tags
  238.  
  239.             TAGS:
  240.                 tags -tdefault.tag $(TAGFLAGS) @project.lst
  241.  
  242.         This would result in all source files in the project being
  243.         tagged every time the executable was generated.
  244.  
  245.  
  246.     2)  The second method is to generate the new tag list for every
  247.         file that is processed at the time that it is processed.
  248.         This method has an advantage in that it will only update
  249.         those files which have changed at each invocation of make and
  250.         it will update every file at the time it successfully
  251.         compiles.  Disadvantages which become a real problem for
  252.         medium to large projects is that targets may share include
  253.         files and thus these include files would be parsed several
  254.         times and there is large overhead when merging the new tags
  255.         into the old tag file which is incurred for every target file
  256.         rather than just once at the end of the make.  An example of
  257.         the way to implement this method in the makefile is given
  258.         below:
  259.  
  260.             .c.obj
  261.                 $(CC) $(CFLAGS) -o $@
  262.                 @echo $< > file.lst
  263.                 !for filename in $**
  264.                     @echo $(filename) >> file.lst
  265.                 !end
  266.                 tags -tdefault.tag $(TAGFLAGS) @file.lst
  267.  
  268.  
  269.     3)  The third is to accumulate filenames within a temporary
  270.         file and to use that file as a LISTFILE on the tags command
  271.         line and to execute the tags executable when the project
  272.         executable in linked.  This method is very good overall
  273.         because no file will be tagged until the end of the make
  274.         (which means you do not have calling and merging overhead to
  275.         worry about) and no file is tagged more than once during a
  276.         make.  This method will also be the fastest over time because
  277.         of the incremental nature of the tagging (notice that the
  278.         list file is deleted after tags is run so that files are
  279.         accumulated until the make succeeds and is then purged for
  280.         the next source change and make cycle).  This method suffers
  281.         in that tags are not generated until a successful make has
  282.         occurred and causes problems when large changes are underway
  283.         (this is usually not a major problem).  An example is given
  284.         below:
  285.  
  286.             .c.obj:
  287.                 $(CC) $(CFLAGS) -o $@
  288.                 @echo $< >> file.lst
  289.                 !for filename in $**
  290.                     @echo $(filename) >> file.lst
  291.                 !end
  292.  
  293.             MYEXE: $(OBJ)
  294.                 $(LINK) $**, $@;
  295.                 tags -tdefault.tag $(TAGFLAGS) @file.lst
  296.                 del file.lst
  297.  
  298.  
  299.     Several make file utilities have feature which make tags a little
  300. easier to implement within the make process and below are suggestions
  301. for optimizing your environment using OPUS make and PolyMake.
  302.  
  303.     1)  Use directives to force your make facility to release as much
  304.         memory as possible for the tags executable.  Tags may take up
  305.         quite a bit of core for large projects during the sort phase.
  306.         Within OPUS make this is accomplished by placing the
  307.         directive after the target and before the colon, for
  308.         instance:
  309.  
  310.             TAGS .MISER: $(SRCS)
  311.                 tags -tdefault.tag $(TAGFLAGS) $**
  312.  
  313.         PolyMake has a separate directive which takes a list of
  314.         executables which are to be given more memory, as an example:
  315.  
  316.             .MEMSWAP cl link tags
  317.  
  318.         Doing this will help with tight memory situations.
  319.  
  320.     2)  Use response files to overcome the limitations of the DOS
  321.         command line.  Normally you will want to generate a response
  322.         file manually in the makefile.  An example of doing this is
  323.         shown in the examples above in the sections dealing with
  324.         tagging methods.  Note that you may not place options within
  325.         the response file.  Only comments and filenames are allowed
  326.         within the response files used by this utility.  Manual
  327.         creation of response files are suggested because of the
  328.         additional control allowed over the the files placed in the
  329.         response file.  For example, it is simple to change the
  330.         response file generator to exclude all *.h files (or some
  331.         other file to be filtered) from the response file.
  332.             OPUS make will automatically create response files for
  333.         specified executables and pass a response file on the
  334.         utilities command line after prepending a '@'.  For example,
  335.         the directive below would place all input files into a
  336.         temporary file and passes the command line to the tags
  337.         executable as "tags @mkXXXXXX.rsp".
  338.  
  339.             .RESPONSE_LINK tags
  340.  
  341.         The response file created will contain all the command line
  342.         for that particular utility, so that if you are specifying a
  343.         tag file or detailing tagging or need to use any switches for
  344.         tags then you need to manually generate a response file (this
  345.         is not a major undertaking).
  346.             PolyMake uses a concept called a local input file to
  347.         allow the semi-automatic creation of response files.
  348.  
  349.  
  350.     3)  Use built in dependency macros to create the new file list to
  351.         tag.  In the example above I used the $** macro which expands
  352.         to all dependency files for the current target.  If your
  353.         environment is such that you have generated a complete tag
  354.         file then you could use the dependency macro $? instead of
  355.         $**.  This will create a list of only those dependency files
  356.         which have actually been changed or are newer than the
  357.         target.  This method assumes that you never delete your tag
  358.         file (without generating a new tag file from a batch file or
  359.         by some other equivalent method).  If you did delete your tag
  360.         file then even if you removed all your object files and
  361.         recompiled, you would probably not get all source files
  362.         tagged correctly (especially include files used by only one
  363.         module which have not changed).  Use of the $? macro is not
  364.         recommended unless your development environment is very
  365.         stable or very large.
  366.  
  367.  
  368.     Included in this distribution is EEL code which has been ported
  369. from the parsers in this utility.  This allows those lucky enough to
  370. be using Epsilon as their programmer's editor to generate these tags
  371. from within their primary editing environments (while this is quite a
  372. bit slower, it is also sometimes very convenient).  Epsilon users
  373. have the additional advantage of using the built in tags package
  374. which is shipped with Epsilon and which is directly supported by this
  375. tags generator.
  376.  
  377.     Also included here is a macro set for brief to use the MicroSoft
  378. Error format tags generated by this utility.  While it is a poor
  379. substitution for built in support, it is a good example of reasonable
  380. ways to do this for extensible editors.
  381.  
  382.     One nice thing which falls out of this code is a very well done
  383. sort routine which is UNIX compatible, highly portable and one of the
  384. fastest I have seen (UNIX, VMS, Ultrix, MSDOS, etc.).  This utility
  385. is automatically made if you make the tags generator or build using
  386. the included makefile.
  387.  
  388. ------------------------------------------------------------------------------
  389.  
  390. Usage: TAGS {[OPTIONS] [FILENAME]}
  391.  
  392. Options Syntax:
  393.  
  394.     -h, -?
  395.  
  396.         Obtain a detailed help screen directed to standard output.  In a
  397.         pinch this will do as a manual if redirected to a file.
  398.  
  399.     @LISTFILE
  400.  
  401.         Use LISTFILE as a "response" file.  This file is a list of
  402.         input filenames.  This file lists filenames (with or without
  403.         wildcards) one at a time and the filenames may be separated
  404.         by '+', ',', ';' or by whitespace.  In addition, comments are
  405.         allowed within the LISTFILE.  Comments are delimited by
  406.         placing a pound sign '#' before the comment.  This is very
  407.         similar to comments allowed in a makefile except that
  408.         comments are allowed on any line or at the end of any line,
  409.         start at the '#' and go to the end of the current line.
  410.         There must be at least one character between the filename and
  411.         the comment character (ie '+', ',', ';' or whitespace) to
  412.         differentiate between the beginning of comment and a filename
  413.         character (since '#' is a valid element of a filename).
  414.  
  415.  
  416.     -x{EXCLUDEFILE|@LISTFILE}
  417.  
  418.         Excludes the files specified by EXCLUDEFILE or excludes all
  419.         files listed in LISTFILE using the same syntax described
  420.         above.
  421.  
  422.  
  423.     -tTAGFILE
  424.  
  425.         Add new generated tags to TAGFILE.  This file may or may not
  426.         exist.  All tags from TAGFILE which were derived from files
  427.         currently being parsed will be removed during the merge
  428.         phase.  This tagfile is assumed to be in one of this
  429.         utilities output formats.  If sorting is specified then new
  430.         tags will be merged in correct order with current case
  431.         sensitivity, otherwise tags will be placed at the beginning
  432.         of the new resulting tag file (this will result in quicker
  433.         responses during tag searches while editing).  if -m or -s
  434.         are used this switch is ignored (all output is to stdout).
  435.  
  436.  
  437.     -lLOGFILE
  438.  
  439.         Output all activity to LOGFILE.  The log file will be created
  440.         in a LISTFILE format (ie. suitable as input using the
  441.         @LISTFILE syntax).  The behavior regarding existing files is
  442.         determined by the case of the switch as follows:
  443.  
  444.             -l (lower case) creates and outputs to a file overwriting
  445.                any currently existing file
  446.             -L (upper case) appends all output to the logfile if
  447.                there is an already existing file
  448.  
  449.  
  450.     -o[options]
  451.  
  452.         This switch is used to determine the output format to the
  453.         output stream.  [options] may be one of the following:
  454.  
  455.          e  Epsilon (>= V6.0) tag format
  456.  
  457.             ( tokenString {tab} fileName {tab} characterOffset {tab} line )
  458.  
  459.             This format is used by the Epsilon editor (V6.x)
  460.             created by Lugaru Software and specifies the token
  461.             identifier, the file name (including full path, normally),
  462.             the character offset of the beginning character (starting
  463.             at character 0) and the line which that offset is located on.
  464.  
  465.          5  Epsilon (<= V5.03) tag format
  466.  
  467.             ( tokenString;fileName;characterOffset )
  468.  
  469.             This format is used by the Epsilon editor (V4.x and V5.x)
  470.             created by Lugaru Software and specifies the token
  471.             identifier, the file name (including full path, normally)
  472.             and the character offset of the beginning character
  473.             (starting at character 0).
  474.  
  475.          g  GNU tag format
  476.  
  477.             ( tokenString {tab} fileName {tab} /$line^/ )
  478.  
  479.             This format is used by GNU's EMACS editor, originally
  480.             written by Richard Stallman and widely used in the UNIX
  481.             community.  This is also the format created by its
  482.             companion utility "ctags" which does very simple function
  483.             header tagging.
  484.  
  485.          s  Space-Delimited format
  486.  
  487.             ( tokenString fileName lineNumber )
  488.  
  489.             This format is the simplest format available and requires
  490.             very little parsing and is very simple to import into
  491.             foreign formats (ie. database formats, etc.).
  492.  
  493.          m  MicroSoft Error format
  494.  
  495.             ( tokenString fileName(lineNumber) )
  496.  
  497.             This format has an advantage in that it has been around
  498.             for quite some time and a fair amount of effort has been
  499.             expended to parse this format and move to the location in
  500.             the source specified during compilation stages.  Many
  501.             macros may be modified to use this type of tag format
  502.             with very minor changes.
  503.  
  504.  
  505.     -a[options]
  506.  
  507.         This switch is used to specify the types of tokens for which
  508.         tags are generated for tagging of assembly files.  All token
  509.         types are tagged as the default ( -afdlmsu ).  Source modules
  510.         are expected in 80x86 assembly using MASM/TASM syntax.  The
  511.         location of the -a switch on the command line is important.
  512.         All files (and files found in LISTFILEs) will be tagged using
  513.         assembly tagging (and the options specified on that switch)
  514.         until another -a or -c switch is found.  Order is not
  515.         important for the options to this switch.
  516.  
  517.          f  procedure labels
  518.  
  519.             ( token proc )( proc token )
  520.  
  521.             This is a mnemonic for function (which has nothing to do
  522.             with a procedure call in assembly, but does well for
  523.             frail human memory.  This option specifies tagging of the
  524.             "proc" keyword.
  525.  
  526.          d  definition labels
  527.  
  528.             ( token equ const )( token db declaration )
  529.  
  530.             This option specifies tagging of defines and definition
  531.             labels such as the tokens "equ", "db", "dq", "dw", "df",
  532.             etc.
  533.  
  534.          l  local labels
  535.  
  536.             ( token label )( label token )( token: )
  537.  
  538.             This option specifies tagging of local labels (labels of
  539.             local file duration).  This includes the keyword "label"
  540.             as well as the shorter ':' notation.
  541.  
  542.          m  macro labels
  543.  
  544.             ( token macro )( macro token )
  545.  
  546.             This option specifies tagging of defined macros using the
  547.             keyword "macro".
  548.  
  549.          s  struc labels
  550.  
  551.             ( token struc )( struc token )
  552.  
  553.             This option specifies tagging of structure definitions
  554.             defined using the keyword "struc".
  555.  
  556.          u  union labels
  557.  
  558.             ( token union )( union token )
  559.  
  560.             This option specifies tagging of union definitions
  561.             defined using the keyword "union".
  562.  
  563.  
  564.     -c[options]
  565.  
  566.         This switch is used to detail the token types to tag in C and
  567.         C++ source files.  All token types are tagged by default
  568.         ( -cdmstekuvcfpxi ).  Source files are expected in standard
  569.         ANSI 2.0 C/C++ syntax.  The location of the -c switch on the
  570.         command line is important.  All files (and files found in
  571.         LISTFILEs) will be tagged using C tagging (and the options
  572.         specified on that switch) until another -a or -c switch is
  573.         found.  Order is not important for the options to this
  574.         switch.
  575.  
  576.  
  577.          d  defines
  578.  
  579.             ( #define token statement )
  580.  
  581.             This option specifies that defines are to be tagged
  582.             (preprocessor defines).  This does not include macros
  583.             which are an extended use of the #define preprocessor
  584.             directive.
  585.  
  586.          m  macro labels
  587.  
  588.             ( #define token() statement )
  589.  
  590.             This option specifies tagging of macros defined via use
  591.             of the preprocessor #define directive.
  592.  
  593.          s  struct globals
  594.  
  595.             ( struct token {} )
  596.  
  597.             This option specifies tagging of structures defined via
  598.             use of the "struct" keyword and implicitly defined within
  599.             C++ syntax variations.
  600.  
  601.          t  typedef globals
  602.  
  603.             ( typedef declaration token, token, ... )
  604.  
  605.             This option specifies tagging of identifiers defined via
  606.             use if the "typedef" keyword.
  607.  
  608.          e  enum globals
  609.  
  610.             ( enum token {} )
  611.  
  612.             This option specifies tagging of enumerations defined via
  613.             use of the "enum" keyword.
  614.  
  615.          k  enum konstants
  616.  
  617.             ( enum { token, token, token, ...} )
  618.  
  619.             Note the cute spelling if constants with a 'k' so that I
  620.             can justify the assignment of this letter.  This option
  621.             specifies tagging of enumeration constants within
  622.             declared enumerations.
  623.  
  624.          u  union globals
  625.  
  626.             ( union token {} )
  627.  
  628.             This option specifies tagging of unions defined via use
  629.             of the "union" keyword.
  630.  
  631.          v  global variable
  632.  
  633.             ( declaration token, token = {}, token, ... )
  634.  
  635.             This option specifies tagging of global variable
  636.             declarations.
  637.  
  638.          c  global class
  639.  
  640.             ( class token: {} )
  641.  
  642.             This option specifies tagging of class definitions
  643.             specified via use of the "class" keyword.
  644.  
  645.          f  function definitions
  646.  
  647.             ( token() declaration {} )
  648.  
  649.             This option specifies tagging of function declarations.
  650.  
  651.          p  prototypes
  652.  
  653.             ( token(); )
  654.  
  655.             This option specifies tagging of prototypes.
  656.  
  657.          x  extern defines
  658.  
  659.             ( extern declaration )
  660.             ( extern "C" declaration )
  661.             ( extern "C" { declaration; declaration; ... } )
  662.  
  663.             This option will specify that tags which have the extern
  664.             storage class are to be output.  The x option is a
  665.             modifier and will only be effective when other options
  666.             are used (ie.  -cpx must be specified to obtain extern
  667.             prototypes, -cx alone yields nothing).  Note also that
  668.             the -cx modifier has no effect for function, define and
  669.             macro tags which are tagged only according only to the f,
  670.             d and m options respectively.  This modifier may be
  671.             placed anywhere within the options list.
  672.  
  673.          i  static declarations
  674.  
  675.             ( static declaration )
  676.  
  677.             This option will specify that tags which have internal
  678.             static storage class are to be output.  The i option is
  679.             a modifier and will only be effective when other options
  680.             are used (ie.  -cvi must be specified to obtain static
  681.             variable declarations, -ci alone yields nothing).  Note
  682.             also that the -ci modifier has no effect for define and
  683.             macro tags which are tagged only according only to the d
  684.             and m options respectively.  This modifier may be placed
  685.             anywhere within the options list.
  686.  
  687.  
  688.     -j
  689.  
  690.         This is the junk filter suppression switch to allow tagging
  691.         of functions and declarations which are overloaded operators
  692.         in C++.  For example, if the junk filters are enabled then
  693.         the declaration "inline myType operator+(MyType m1, MyType m2);"
  694.         would not be tagged for "+" which is normally a standard C 
  695.         delimiter token and operator.
  696.  
  697.  
  698.     -q
  699.  
  700.         This is the quiet switch and will suppress normal status
  701.         output to stderr and program version information.
  702.  
  703.  
  704.     -r
  705.  
  706.         This switch will suppress the default output of the full file
  707.         path name and will specify the use of relative pathnames in
  708.         the generated output.
  709.  
  710.  
  711.     -n
  712.  
  713.         This switch will suppress sorting of the tag output (Often
  714.         used in conjunction with GNU or Epsilon style tags)
  715.  
  716.  
  717.     -i
  718.  
  719.         This switch specifies the use of a case sensitive sort
  720.         (Normally a case insensitive sort is used).  I know, the
  721.         character 'i' is normally used for switching to a case
  722.         insensitive behavior, things are tough all over, you'll learn
  723.         to live with it.
  724.  
  725.  
  726.     -m
  727.  
  728.         This option specifies a merge sort of the existing files
  729.         which are parsed as a result of the command line.  All of
  730.         these files are assumed to be sorted in the current style.
  731.         Note that this switch results only in the merge of the input
  732.         files (no tagging is done).  Output is to stdout only (-t is
  733.         ignored) when using this switch.
  734.  
  735.  
  736.     -s
  737.  
  738.         This options specifies that all input files are to be sorted
  739.         only.  All files are assumed to be in an unsorted state.
  740.         Note that this switch results only in sorting of the input
  741.         files (no tagging is done).  Output is to stdout only (-t is
  742.         ignored) when using this switch.
  743.  
  744. ------------------------------------------------------------------------------
  745.  
  746. Notes:
  747.  
  748.     The TMP environment variable is used for temporary files.
  749.  
  750.     The default for tags is to use C style tagging, the Epsilon tag
  751. file format, to sort the output before finally placing it in the
  752. output file (or stdout if -t is not used) and to be verbose and log
  753. activity to stderr.
  754.  
  755.       Each file specified on the command line or within a LISTFILE
  756. will be tagged only once regardless of the number of times it appears
  757. on the command line (This includes LISTFILEs as well as filenames and
  758. the files listed within LISTFILEs).
  759.  
  760.       All of the switches may be specified anywhere on the command
  761. line and with the exception of the style switches (-a, -c) are not
  762. position dependent.  The style switches are active only for input
  763. files which fall after them on the command line (or in a LISTFILE
  764. specified after the switch).This allows the specification of
  765. different tagging styles and types on a file by file basis.
  766.  
  767.       Input file specifications allow the use of *IX shell style
  768. expressions.  This allows input filenames such as "*", "*t?*.c" and
  769. "*[e-gxyz]*".  Note that "*" in this case is completely equivalent to
  770. "*.*" in normal DOS usage. The use of "*." will obtain files without
  771. extensions.
  772.  
  773.       This utility performs a CRC validation on itself to prevent
  774. corruption and viral infection from outside influences.  Modification
  775. of this file in any way will result in a failure of the internal CRC
  776. check.  On CRC failure the program will exit with a warning message.
  777.  
  778.  
  779. ------------------------------------------------------------------------------
  780.  
  781. Caveats:
  782.  
  783.     1) Long lines will cause the buffer count output by the epsilon
  784.        tags format to be incorrect for ASM files.  A long line is
  785.        defined as one over 255 characters in length.  Line counts and
  786.        line outputs will maintain correct behavior (ie. effects only
  787.        Epsilon style output).  Long lines may also cause a mistag.
  788.  
  789.     2) Long tokens in excess of 4K in length will cause the buffer
  790.        count in the C token parser to be incorrect.  Line counts and
  791.        line outputs will maintain correct behavior (ie. effects only
  792.        Epsilon style output).  These large tokens may also cause a
  793.        mistag.
  794.  
  795. ------------------------------------------------------------------------------
  796.  
  797. Known Bugs:
  798.  
  799.     1) Use of unbalanced parens in ifdef'd C/C++ code blocks can cause
  800.         problems, some methods are used to deal with this but
  801.         examples such as
  802.  
  803.             #ifdef FOO
  804.  
  805.                 StrangeProc();
  806.             } /* end if function declaration */
  807.  
  808.             #else
  809.  
  810.                 ElseStrangeProc();
  811.             } /* end of function declaration */
  812.  
  813.             #endif
  814.  
  815.         would result in a prototype tag of ElseStrangeProc.
  816.  
  817.     2) Use of unbalanced quotes in comments within _asm code blocks could
  818.         cause the parser to miss a close brace.  For instance
  819.  
  820.             _asm {
  821.                 mov ax,cx   ; blah
  822.                 sub ax,1    ; blah, blah
  823.                 call __foo  ; do not put a single quote here '
  824.             }
  825.  
  826.         will result in a miss of the '}' since the parser is expecting a
  827.         token of the form 'c' where c is one of the standard character
  828.         expressions.  As another example
  829.  
  830.             _asm {
  831.                 mov ax,cx   ; blah
  832.                 sub ax,1    ; blah, blah
  833.                 call __foo  ; an unbalanced quote here " will cause chaos
  834.             }
  835.  
  836.         will produce a situation where the parser merrily chugs along until
  837.         it finds another double quote and this will propagate until another
  838.         unbalanced double quote is found.  Both of these cases will most
  839.         likely result in the loss of all tagging information for the current
  840.         file after the point at which the offending code was found.
  841.  
  842. ------------------------------------------------------------------------------
  843.  
  844. Implementation:
  845.  
  846. The file MANIFEST.DOC describes the files in this distribution.
  847.  
  848. This project was developed using the MicroSoft C Compiler V6.00A with
  849. elements compiled previously under TC, TC++ and BC++.  A port to
  850. other compilers should not be difficult.  The sort module has been
  851. compiled using many different UNIX compilers and the code is under
  852. GNU CopyLeft.  All of the other source files and documentation files
  853. are dedicated to the Public Domain.
  854.  
  855. Some things to be aware of:
  856.  
  857.     This module is compiled using the /G2 option.  This means that
  858. only those using AT (80286) and later class machines may use the
  859. executable supplied with this distribution.  For those still
  860. unfortunate enough to be developing on an XT class machine, you will
  861. need to recompile with the /G0 switch enabled.
  862.  
  863.  
  864.     If you are using a MicroSoft compiler previous to V6.00 then you
  865. should remove the /Og (global optimization) switch from the makefile.
  866. The versions of the MicroSoft C compiler before V6.00 occasionally
  867. had problems with code generation when a routine was too large for
  868. global optimization (these sources have several such routines).
  869.  
  870.  
  871. If you port this to another compiler, place the changes in #ifdef'd
  872. code blocks or create a context sensitive diff file and send it on to
  873. me.  I will then incorporate the changes and make sure that these
  874. changes get circulated in a new release.
  875.  
  876.  
  877. Questions?  Comments?  Accolades?  Insults?  Send them to me and I'll
  878. see what I can do.  I hope you find good use for this utility and
  879. code.
  880.  
  881.                                     jbk
  882.